home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / ibmcom.zip / IBMCOM.DOC < prev    next >
Text File  |  1989-04-29  |  7KB  |  186 lines
  1.             I B M C O M                           
  2.  
  3. IBM RS232 interrupted driven communications routines. BBS version
  4. has small model lib file for ibmcom. 
  5.  
  6. Since the BBS version supplies only object,the following assumptions
  7. have been made:
  8.  
  9.         o Buffer input size is defined to be 2000 characters per 
  10.           port.
  11.  
  12.         o Buffer output size for putsi_com() routine is defined to be 
  13.           80 characters.
  14.  
  15. Purchasers of the source can change the above buffer size's.  If you
  16. whish to obtain source and/or to see these routines continue to be
  17. supported with ehancements,bug fixes, protocals, terminal
  18. emulators,etc.
  19.  
  20.   Send $15 to:                                
  21.  
  22.     Intrinsic Computers                 
  23.     RR 4                                
  24.     Oak Ridge,NJ   07438                        
  25.  
  26.      Send $25 and we'll give you the latest   
  27.      version on a diskette plus code for a    
  28.          reentrant xmodem recieve protocal. We    
  29.      also are available for consulting.            
  30.  
  31.  
  32.  Description of Routines:
  33.  
  34.   int init_handl( int port_num)                        
  35.      Initializes port_num interrupt routines.         
  36.      Must be called after init_port(),but before     
  37.      using any other routines. Returns FALSE if
  38.      port_num is not 1 thru 4,otherwise TRUE.
  39.                                     
  40.   void init_buffer_out(int port_num)                   
  41.      Sets up the circular buffers for interrupt   
  42.      output (specifically putsi_com()).  Should   
  43.      be called only once.                         
  44.                                     
  45.   int init_port(int port_num,int baudrate,char parity,
  46.         int data_bits,int stopbit)                        
  47.      Must be called before init_handl(). It sets    
  48.      the port_num's baud rate,parity,etc..            
  49.   Variables used:
  50.         port_num   1,2,3, or 4
  51.         baudrate   3 or 300   for 300 baud
  52.                    6 or 600   for 600 baud
  53.                   12 or 1200  for 1200 baud
  54.                   24 or 2400  for 2400 baud
  55.                   48 or 4800  for 4800 baud
  56.                   96 or 9600  for 9600 baud
  57.                   19 or 19200 for 19200 baud
  58.                   38 or 38400 for 38400 baud
  59.                   56          for 56000 baud
  60.                  112          for 112000 baud
  61.         parity    'E' for even
  62.                   'N' for none
  63.                   'O' for odd
  64.         data_bits  5,6,7, or 8
  65.         stopbit    1 or 2
  66.   Returns
  67.         TRUE if params ok.
  68.         FALSE if illegal params.
  69.                                     
  70.   int check_port_hw(int port_num) 
  71.                         
  72.      Used to check if a port error has occured or    
  73.      if no error it returns the number of char        
  74.      in the ports interrupt buffer. If error has
  75.      occurred it returns the NEGATIVE of the port's
  76.      line control register.  In programmers terms
  77.      if the return value is >= 0 you got the # chars
  78.      in port_num's buffer, otherwise if its < 0, you
  79.      got an error on the port.  The error is cleared
  80.      by calling this routine.
  81.                                     
  82.   int check_port_buf(int port_num)                    
  83.  
  84.      Returns port_num's buffer overflow status.    
  85.         1 for yes its overflowed
  86.         0 for no overflow
  87.                                     
  88.   unsiged com_status(int port_num)                        
  89.      Returns port_num's port status.                
  90.                                     
  91.   void disable_txmit_int(int port_num)             
  92.             
  93.      Turns off interrupt driven output. You DON'T 
  94.      call this unless you want to stop midstream  
  95.      the output of a string. Normally the         
  96.      interrupt handler inself will turn off Tx    
  97.      interrupts when it finishes the string.      
  98.                                                   
  99.   int disable_port_int(int port_num)                      
  100.  
  101.      Turns off interrutps for port_num. Returns FALSE if
  102.      illegal port_num, otherwise TRUE.
  103.                                     
  104.   int reset_port(int port_num)
  105.  
  106.      Resets port_num so that it will not interrupt
  107.      the IBM anymore. Used to halt communications 
  108.      Should be called before exiting your programs
  109.      or interrupts will still be active and            
  110.      hang the machine (or worse). Returns FALSE if illegal
  111.      port_num, otherwise TRUE.
  112.                                     
  113.   void putc_com(int port_num,char *string)                        
  114.  
  115.      Outputs the string to port_num    
  116.      Does not buffer the character. It uses a        
  117.      polling technique.                               
  118.                                     
  119.   int puts_com(int port_num,char *string,int num_char)                
  120.  
  121.      Outputs the indicated num_char from string   
  122.      to port_num using a polling technique. Returns
  123.      TRUE.
  124.                                     
  125.   int putsi_com(int port_num,char *string,int num_char)                
  126.  
  127.      Same as puts_com() except it outputs the     
  128.      string using an interrupt driven technique.  
  129.      You must call init_buffer_out() once before  
  130.      ever using putsi_com. Returns TRUE if able to
  131.      handle the string passed to it, otherwise FALSE.
  132.      See the demo program for further explanation.
  133.                                     
  134.   unsigned char getc_com(int port_num)                        
  135.  
  136.      Gets a char from port_num's buffer.If the    
  137.      buffer is empty it returns 0xFF which could    
  138.      be a valid character. This routine should be    
  139.      used in conjunction with check_port_buf() to    
  140.      see if any characters are in the buffer     
  141.      before calling this routine. Returns char gotten.
  142.                                 
  143.   int gets_com(char *buffer,int num_bytes,int port_num)            
  144.  
  145.      Gets num_bytes from port_num and puts it into buffer. 
  146.      Returns actual number of bytes transferred into buffer.
  147.                                 
  148.   void report_serial_status(unsigned error_code)            
  149.  
  150.      Will print out a nice report of the port status if you pass    
  151.      it the port status (obtained from com_status(). Note, not 
  152.      all status bits are errors, some are normal.
  153.                                 
  154.   int set_porthw_parm(int port_num, int port_ad,       
  155.                  int vector_num, unsigned char    
  156.                  mask)                            
  157.                                                   
  158.      Sets port_num hardware address parameters    
  159.      where port_ad is the base hardware address   
  160.      of the port, vector_num is the interrupt     
  161.      number, and mask is the mask for the 8259    
  162.      PIC. This routine generally is not needed    
  163.      for ports 1 & 2, however since ports 3 & 4   
  164.      hardware addressing is not standard this     
  165.      routine will allow you to change these       
  166.      parameters if your particluar hardware is    
  167.      different than the following defaults:       
  168.                                                          
  169.        Port 3 base hardware ad = 0x3e8            
  170.               vector number    = 12               
  171.               mask             = 0xef             
  172.                                                          
  173.        Port 4 base hardware ad = 0x2e8            
  174.               vector number    = 11               
  175.               mask             = 0xf7    
  176.          
  177.      Returns TRUE if port_num is 1 tru 4,otherwise
  178.      FALSE.
  179.  
  180.   Linking Instructions:                    
  181.  
  182.      Must be linked with a main().  Supplied object in 
  183.      BBS version is small model only.
  184.                                 
  185.  
  186.